package cz.muni.fi.pa165.musiclibrary.api.service;

import java.util.List;

import javax.annotation.Nonnull;
import javax.annotation.Nullable;

import cz.muni.fi.pa165.musiclibrary.api.service.dto.IAlbumDTO;

/**
 * Service interface for working with albums.
 * 
 * @author Maros Kucbel
 * @date 2012-10-28T15:12:43+0100
 */
public interface IAlbumService {

    /**
     * Create new album.
     * 
     * @param album Album to be created.
     * @param userName User name.
     * @throws IllegalArgumentException If parameter is {@code null}.
     */
    void create(final IAlbumDTO album, String userName);
    
    /**
     * Edit album.
     * 
     * @param album Album to be updated.
     * @param userName User name.
     * @throws IllegalArgumentException If parameter is {@code null}.
     */
    void update(final IAlbumDTO album, String userName);
     
    /**
     * Delete album.
     * 
     * @param album Album to be removed.
     * @param userName User name.
     * @throws IllegalArgumentException If parameter is {@code null}.
     */
    void delete(final IAlbumDTO album, String userName);
     
    /**
     * Return album with given identifier or {@code null}, if none exists.
     * 
     * @param id Identifier.
     * @return Album with given identifier or {@code null}, if none exists.
     * @throws IllegalArgumentException If parameter is {@code null}.
     */ 
    @Nullable
    IAlbumDTO getById(final Long id);
    
    /**
     * Return all albums. 
     * Never returns {@code null}, if there are no albums returns empty list.
     * 
     * @return List of all albums.
     */
    @Nonnull
    List<IAlbumDTO> getAll();
    
     /**
     * Return list of albums whose title contains given string of characters.
     * Never returns {@code null}, if there are no albums returns empty list.
     * 
     * @return List of albums.
     * @throws IllegalArgumentException If parameter is {@code null}.
     */
    @Nonnull
    List<IAlbumDTO> getByTitle(final String title);
}
